feat(react-query): add optional @types/react peer dependency 🤖🤖🤖 - #11598

🎯 Changes

Adds @types/react as an optional peer dependency of @tanstack/react-query, at *:

"peerDependencies": { "@types/react": "^18 || ^19", "react": "^18 || ^19" },
"peerDependenciesMeta": { "@types/react": { "optional": true } }

Why

The published package ships declaration files that import React's types — import * as React from "react" appears in build/modern/useQuery.d.ts, QueryClientProvider.d.ts, HydrationBoundary.d.ts and eight others in 5.103.2 — but the package only declares the react runtime peer.

TypeScript resolves a package's imports from where that package physically sits on disk, and it ignores NODE_PATH. Most pnpm layouts hide this, because the virtual store lives inside the consumer's own node_modules and the lookup walks up into it. With virtualStoreType: global, though, the package physically lives outside the consumer's repository, e.g. ~/Library/pnpm/store/v11/links/@/react-query/<version>/<hash>/node_modules/@tanstack/react-query. From there @types/react is not reachable, so react resolves to the untyped runtime entry instead:

======== Resolving module 'react' from '<store>/@tanstack/react-query/build/modern/useQuery.d.ts'. ========
======== Module name 'react' was successfully resolved to '<store>/react/index.js' with Package ID 'react/index.js@19.3.0'. ========

index.js, not index.d.ts. With allowJs: true that is silently accepted and every React-derived type in the public surface degrades to any — ReactNode, the children of QueryClientProvider and HydrationBoundary, the ref and element types threaded through the hooks. Zero compiler errors; tsc still exits 0. That silence is the reason this is worth fixing. Where a consumer's config blocks the JS fallback it fails outright instead.

Declaring the optional peer makes that same resolution land on the consumer's @types/react/index.d.ts.

I verified the effect end to end on a real application by injecting these peers through pnpm packageExtensions: it went from 61 untyped + 6 unresolved React resolutions to 1012/1012 landing on .d.ts, with tsc still exiting 0.

Why it's safe

• Optional, so consumers not using TypeScript get no install warning and nothing in their lockfile.
• ^18 || ^19, mirroring the existing react peer exactly, so the types peer makes no version claim the runtime peer does not already make. The repo develops against @types/react@^19.2.7; the union keeps React 18 consumers valid.
• Runtime behaviour is completely unchanged — this is a manifest-only change.

Precedent

@testing-library/react declares exactly this pair. Within this repo, #10007 did the same thing for typescript in @tanstack/eslint-plugin-query, and I matched that package.json's key ordering and shape here.

Scope

Deliberately limited to @tanstack/react-query. react-query-devtools, react-query-persist-client and react-query-next-experimental look like they have the same gap, but I kept this to one package per the contributing guide — happy to extend it here or follow up separately, whichever you prefer.

A patch changeset is included.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request. — manifest-only change with no source or test impact; validated the JSON and checked both files against Prettier.
• I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes
  • Improved TypeScript compatibility for React Query consumers by declaring React type definitions as an optional peer dependency. React’s existing supported version range is unchanged, and projects can continue using the types provided by their own installation.